home *** CD-ROM | disk | FTP | other *** search
/ Shareware Overload Trio 2 / Shareware Overload Trio Volume 2 (Chestnut CD-ROM).ISO / dir36 / batmouse.zip / BATMOUSE.TXT < prev    next >
Text File  |  1993-08-22  |  21KB  |  386 lines

  1.  
  2.  
  3.  
  4.        INTRODUCING "BATMOUSE" - A MOUSE FOR YOUR BATCH FILES
  5.  
  6.  
  7.  
  8.        Have you ever wondered what makes a batch file seem slow at times
  9.        or have you tried to write a batch file and given up in
  10.        frustration?  Did you ever think you might like to have multiple
  11.        batch file menus or to interface your batch file with keyboard
  12.        responses?  Better yet, interact with your mouse?  Read on.
  13.  
  14.        If you use DOS programs exclusively or if you use Windows and
  15.        occasionally need to go to DOS to use some other program.
  16.        BATMOUSE and DIRECTOR.BAT provide a means to display a
  17.        sophisticated menu from within a batch file and are completely
  18.        compatible with all programs.  You may invoke Windows from
  19.        DIRECTOR.BAT and exit Windows temporarily to DIRECTOR.BAT,
  20.        execute an otherwise Windows compatible program, return to the
  21.        DIRECTOR and then return to Windows - no problem.
  22.  
  23.        DOS dos not have a good reputation for user friendliness, and the
  24.        batch file interpreter is not much better.  That's why there are
  25.        many programs around that will help you interface with your batch
  26.        files - programs like BATMOUSE and DIRECTOR.BAT.
  27.  
  28.        DIRECTOR.BAT is an accumulation of ideas for batch files that
  29.        ultimately led to the development of the mouse interface program
  30.        BATMOUSE.  Simply put, BATMOUSE is a standalone program that may
  31.        be called from any batch file or from DOS; it causes the mouse
  32.        cursor to appear seamlessly and reacts to any keyboard input and
  33.        to the movements/clicks of your mouse.
  34.  
  35.        Communications between any batch file and BATMOUSE are conducted
  36.        via the environment variables HR & VC (for horizontal row &
  37.        vertical column) for a mouse click and the testing of ERRORLEVEL
  38.        for the last key pressed.
  39.  
  40.        BATMOUSE checks the environment for variables HR & VC in order to
  41.        set the mouse position to that which was clicked on the during
  42.        the last execution of the program, if there was one.  This is
  43.        performed at startup unless the environment variables have not
  44.        been previously set or have been set to a "-", in which case the
  45.        mouse appears in the center of the screen.  BATMOUSE always sets
  46.        HR & VC to a "-" when the user presses a key instead of a mouse
  47.        button.  This allows the batch file to discern which kind of
  48.        interpretation to make - mouse coordinate or key press.  If
  49.        either HR or VC = "-", the user last pressed a key.  Mouse screen
  50.        coordinates are 1,1 for the upper left corner and 25,80 (HR,VC
  51.        respectively) for the lower right corner.
  52.  
  53.        The DIRECTOR batch file may be used with or without a mouse.
  54.        However,  one of its greatest features is the integration of the
  55.        mouse interface program BATMOUSE.  Used without a mouse,
  56.        DIRECTOR.BAT requires the use of a program available on most
  57.        bulletin boards called REPLY.COM or KEYPRESS.COM.  They have been
  58.        described in numerous magazine articles and will not be discussed
  59.        here.  If you are currently using one of these programs with your
  60.        batch files, your existing batch file should work seamlessly with
  61.        BATMOUSE since the key values returned are identical.
  62.  
  63.        A complete listing of DIRECTOR.BAT with line reference numbers is
  64.        found in file DIRECTOR.TXT.  The line sequence numbers found in
  65.        the left column of this listing are provided in order to
  66.        understand the following references to the descriptions of its
  67.        functions  and should be removed if you plan to use this example
  68.        to create your own batch file.
  69.  
  70.        DIRECTOR.BAT is sensitive to seven parameters (%1 %2 %3 %4 %5 %6
  71.        %7).  If you do not pass parameters the defaults of black and
  72.        white are used.  This allows you to pass only as many parameters
  73.        as you require - if you pass only parameter one, a particular
  74.        background screen will be painted and all the text will be white
  75.        on black.  The program SHOW (line 211) will paint any of 17
  76.        predefined background screens - the screen names are DIRSCN (B&W
  77.        or default use) and DIRSCN00-DIRSCN15 (various color
  78.        combinations).  Therefore, if parameter one (%1) contains 00 or
  79.        01 or 02 ∙∙∙∙ 15, the corresponding screen will be displayed;
  80.        hence, SHOW DIRSCN%1.
  81.  
  82.        The remaining six parameters are used to paint certain text
  83.        portions of the menu:
  84.  
  85.             -    %2 & %3 (foreground/background) are used to paint your
  86.                  personal menu title.
  87.             -    %4 & %5 (foreground/background) are used to paint the
  88.                  function key information.
  89.             -    %6 & %7 (foreground/background) are used to paint the
  90.                  program names at each line of the menu and the menu
  91.                  page number.
  92.  
  93.        Each of the above color parameters may be created using the color
  94.        combinations for foreground and background.  The following
  95.        information is derived from the documentation for ANSI.SYS:
  96.  
  97.             Foreground Colors:
  98.  
  99.                  30 - Black
  100.                  31 - Red
  101.                  32 - Green
  102.                  33 - Yellow (which is brown unless BOLD is on)
  103.                  34 - Blue
  104.                  35 - Magenta
  105.                  36 - Cyan
  106.                  37 - White
  107.  
  108.             Background Colors (bold does not affect these colors):
  109.  
  110.                  40 - Black
  111.                  41 - Red
  112.                  42 - Green
  113.                  43 - Brown
  114.                  44 - Blue
  115.                  45 - Magenta
  116.                  46 - Cyan
  117.                  47 - White
  118.  
  119.        Try some of the following calls to the DIRECTOR:
  120.  
  121.                      %1 %2 %3 %4 %5 %6 %7
  122.  
  123.             DIRECTOR 00 33 44 37 47 37 44
  124.             DIRECTOR 00 33 46 37 47 37 44
  125.             DIRECTOR 06 33 37 37 47 37 41
  126.             DIRECTOR 08 33 47 37 47 37 41
  127.             DIRECTOR 08 33 40 37 47 37 41
  128.  
  129.        Also, be sure to type DEMO to see all the background screens and
  130.        some of the possible color combinations.
  131.  
  132.        Let's begin our analysis of DIRECTOR.BAT with line 2; this line
  133.        allows the DIRECTOR to be aware that the current state of the
  134.        screen is unknown and should be repainted completely.  Line 3 is
  135.        required if you have more than one menu screen to display (we are
  136.        dealing with 3).  If the condition is true, it is implied that
  137.        the environment variable %MENU% is equal to something other than
  138.        'x'  and therefore has been previously used; ie, the batch file
  139.        is returning from a DOS based call or from an exit to DOS and the
  140.        subsequent call of DIRECTOR.  It then branches to the MAINMENU
  141.        label found on line 24 where the screen is then completely
  142.        repainted (line 28) and the appropriate program menu is displayed
  143.        based on %MENU% (in this case 1, 2 or 3).  DIRECTOR always
  144.        returns from DOS and presents the last menu or menu 1 if this is
  145.        the first time in.
  146.  
  147.        Upon return from a calling program or calling DIRECTOR from the
  148.        command line, note that line 2 sets the variable SCRN to 'on'
  149.        (case sensitive).  This causes line 28 to branch (GOTO) to the
  150.        SCN label (line 207) which causes the screen to be painted with a
  151.        predefined screen (line 211).  The program SHOW on this line will
  152.        paint any of 17 predefined screens as discussed above.
  153.  
  154.        The use of lines 209 through 225 require some understanding of
  155.        the use of ANSI.SYS - the DOS 5.0 manual (pages 593-599) provide
  156.        an in depth review which is not possible here.  An overview of
  157.        those lines follows:
  158.  
  159.             Line 209 -     Sets the cursor position to the upper left
  160.                  corner or position (0,0) which is not the same as
  161.                  BATMOUSE (1,1).  Testing of this feature suggests that
  162.                  both 0,0 and 1,1 paint from the upper left corner
  163.                  (contrary to the Microsoft documention) while it is
  164.                  implied that 1,1 is below and to the right 1 character.
  165.             Line 210 -     Clears the line to the right of the current
  166.                  cursor position.
  167.             Line 211 -     Shows a screen as described above.
  168.             Line 212 -     Sets up a bold color combination based on
  169.                  parameters 2 and 3; hence %2 and %3.  The 1 on the left
  170.                  determines bold which only affects the foreground
  171.                  color.
  172.             Line 213 -     Paints text (with the color from line 212) at
  173.                  screen line 3, column 2 - don't hesitate to change the
  174.                  text to something more suitable.
  175.             Line 214 -     Sets up a bold color combination (used with
  176.                  lines 215-225) based on parameters 4 and 5; hence %4
  177.                  and %5.  The 1 on the left determines bold.
  178.             Line 226 -     Causes a branch (GOTO) to %menu% (either 1
  179.                  (line 30), 2 (line 42) or 3 (line 54)) where the
  180.                  specific menu items for the current menu page are
  181.                  painted (lines 30-65) using parameters 6 and 7.  The
  182.                  program references contained in these lines should be
  183.                  modified to support the needs of the user.  Control is
  184.                  the passed to line 65 (ENDSCR) where the color is set
  185.                  to white on black (line 66), the cursor turned on (line
  186.                  67) and BATMOUSE is called (line 69) and the user must
  187.                  click a mouse button or press an appropriated key.
  188.  
  189.        If you use a lot of remarks in your batch file you will find that
  190.        your batch files will execute much faster if you place statements
  191.        to branch (GOTO) around them as found on line 4.  A first time
  192.        call on DIRECTOR branches to MENU1 where MENU is set to 1 and
  193.        control is passed to MAINMENU on line 24.
  194.  
  195.        The lines from 8 to 23 are Page UP & Page DOWN controls and cause
  196.        the program to branch based on which menu page is currently being
  197.        displayed.  The mouse cursor may also be used to invoke this code
  198.        if the user clicks the mouse button while the mouse cursor is on
  199.        the upper or lower 3 lines of the screen - see lines 90-95.
  200.        Lines 90 & 91 test for the top and bottom of the screen
  201.        respectively and because they are the most likely lines to be
  202.        clicked on, they are placed at the beginning of the tests for
  203.        Page UP and Page DOWN - this speeds up the process.
  204.  
  205.        The keyboard keys Page UP & Page DOWN return codes in ERRORLEVEL
  206.        that conflict with the codes for "I" & "Q" respectively, and
  207.        therefore are not used in this example.  There is no reason not
  208.        to use them if you are not also using "I" & "Q"; remember these
  209.        keys will be tested as equals to Page UP and Page DOWN.  A more
  210.        complete list of codes may be found in most technically oriented
  211.        program documentation and in the various DOS manuals - see page
  212.        632 of the DOS 5.0 manual.
  213.  
  214.        At the MAINMENU label found on line 24, the drive and directory
  215.        are immediately set (lines 25 & 26) just in case they were not
  216.        reset by a called program or batch file.  If you plan to use some
  217.        other drive/directory as a base to work from, change line 25/26
  218.        appropriately.
  219.  
  220.        Program BATMOUSE (line 69) is called.  BATMOUSE then waits for a
  221.        mouse or keyboard response, all the while moving the mouse cursor
  222.        appropriately.
  223.  
  224.        Line 70 determines whether the user has pressed a key or  has
  225.        clicked a mouse button.  The environment variable VC is tested
  226.        for not being a "-" which, if true, would indicate a mouse button
  227.        was pressed.  If true (ie, not a "-"), DIRECTOR.BAT branches to
  228.        the MOUSE label on line 89 where the initial tests for Page UP &
  229.        Page DOWN are conducted as described above.
  230.  
  231.        Conversely, if VC contains the value "-" control is passed to the
  232.        next line (71 in this case) where the first tests are for the
  233.        values 'H' or 'h' for HELP.  A brief display of the help screen
  234.        (lines 204-206) occurs, the user presses a key or mouse button
  235.        and the complete screen is regenerated beginning at line 207.
  236.  
  237.        Immediately following the check for help is a check for the F10
  238.        key (line 73) which is a menu item for Page DOWN.  Several tests
  239.        for an exit to DOS are made (lines 74-77); they test for 'Q',
  240.        ESC, F9 and 'q' respectively and cause a branch to F9 (line 227).
  241.        The F9 label (EXIT TO DOS) sets up the echo command which causes
  242.        a screen clear when line 230 is invoked.
  243.  
  244.        At this point it is likely the user wants to run a program and we
  245.        need to prepare for repainting the screen - line 87 makes that
  246.        preparation by setting the environment variable SCRN to 'on'
  247.        (case sensitive).
  248.  
  249.        Lines 79-86 check which key (F8-F1 respectively) was pressed and
  250.        branch accordingly.  A discussion of how the 'program' branching
  251.        works follows below.
  252.  
  253.        Any other key causes a branch to BADKEY on line 125.  Line 126
  254.        causes a beep on your PC's speaker.  The character that you see
  255.        is the ASCII bell character # 7 - it can generally be produced
  256.        with your word processor by pressing and holding the ALT key and
  257.        then pressing the 7 key on the numeric key pad on the right side
  258.        of your keyboard or a special menu found in some of the newer
  259.        WINDOWS programs.  It is sometimes a non-printable character.
  260.  
  261.        Control then bypasses MAINMENU and branches (line 128) to REENTER
  262.        (line 68) where BATMOUSE is called and the process starts again.
  263.  
  264.        Lines 99-113 test for a valid range of VERTICAL COLUMNS (VC)
  265.        which may be expanded or reduced to suit one's needs.  The test
  266.        in this case is for a vertical range because the menu is
  267.        presented vertically.  A resulting valid test on one of these
  268.        lines forces a branch to the the CALLPROG label on line 115 where
  269.        tests on HR are performed (lines 117-124).
  270.  
  271.        A true comparison on any one of these tests causes a branch to a
  272.        label corresponding to the combination of the key pressed and the
  273.        screen (page) being presented.
  274.  
  275.        Look more closely at lines 79-86 (keyboard) and lines 117-124
  276.        (mouse); the branch-to location is determined by the
  277.        concatenation of two variables.  One is a literal that is based
  278.        on which key was pressed or which position of the screen was
  279.        clicked on with the mouse (in this case F1-F7) and the other is
  280.        the value of the environment variable MENU.  MENU should only be
  281.        set by DIRECTOR.BAT and must be 1, 2 or 3 unless you are adding
  282.        more pages to the menu.  Therefore, all program call labels in
  283.        the menus are named "Fnn" (lines 129 to 203).  Line 129 ("F11")
  284.        represents key F1 pressed/selected from menu page 1 while line
  285.        197 ("F73") represents key F7 pressed/selected from menu page 3.
  286.  
  287.        There are three ways of setting up the call of a menu program
  288.        selection;  1)  use CALL to execute batch files (call is not
  289.        required if a batch file call is the last line in the calling
  290.        batch file) from within a batch file (line 189); 2)  use the
  291.        program name directly (line 187) or;  3)  use SET
  292.        PROGTODO=<program name or batch file name> and exit DIRECTOR via
  293.        the GOTO END (lines 178-179).  Note that the label END does not
  294.        clear the screen which makes for a more seamless transition to
  295.        your program.  Be sure to set the appropriate directory when
  296.        required;  either in-line (line 156) or in your external batch
  297.        files.  External batch files called from the DIRECTOR should not
  298.        call the DIRECTOR while those that are invoked using the PROGTODO
  299.        mechanism should call DIRECTOR as the last statement (command)
  300.        and should not use the CALL option.  Use the statement DIRECTOR.
  301.  
  302.        Some discussion as to how the PROGTODO mechanism (line 230)
  303.        functions is in order.  Since the command is not one of the
  304.        internal batch file commands it is interpreted to be an external
  305.        file name and since it is enclosed in %∙∙∙∙%, the batch file
  306.        intepreter will first determine the contents of %PROGTODO%.
  307.        Therefore, upon exit from DIRECTOR, DOS will invoke the contents
  308.        of PROGTODO.
  309.  
  310.        Suppose you want to install your first program in DIRECTOR.BAT
  311.        and that you want to use the empty line F8 on menu page 1 for
  312.        that purpose.
  313.  
  314.        It would be beneficial to have a copy of DIRECTOR.TXT
  315.        (DIRECTOR.BAT with line reference numbers).  From the DOS command
  316.        line type the following:   COPY DIRECTOR.TXT LPT1
  317.        That should print a copy of DIRECTOR.TXT on the printer connected
  318.        to the default printer port of your PC.
  319.  
  320.        The following steps will assist you in converting DIRECTOR.BAT to
  321.        meet your personal requirements (make sure overtype is on or
  322.        insert is off on your word processor):
  323.  
  324.             ∙    Consider changing the text
  325.                  P E R S O N A L  D I R E C T O R  on line 213 to
  326.                  something like your company name or
  327.                  "J O H N'S  D I R E C T O R".
  328.             ∙    Review the text beginning at line 30 thru line 39.
  329.                  These are the lines that represent the specific program
  330.                  displays of menu page one.  Line 32 represents F1 and
  331.                  line 39 represents F8.  Be aware that there are
  332.                  trailing spaces beyond the program reference - some
  333.                  word processors do not display the line feed/carriage
  334.                  returns found at the end of the all lines in ASCII
  335.                  files.  The idea here is to avoid affecting the
  336.                  alignment of the spaces which provide an on screen
  337.                  visual organization.
  338.             ∙    Insert the text you want to display on screen beginning
  339.                  on line 39 just under the 'P' in 'PAINT BRUSH'.
  340.             ∙    Note that the label  (line 150) for this menu page and
  341.                  F-KEY is F81.  As discussed above, F8 is for the key F8
  342.                  and 1 is for menu page 1.  Just after line 150 and
  343.                  before line 151 you must insert at least one if not
  344.                  more lines.  This can be done with most word processors
  345.                  by turning on insert (overtype is off), placing the
  346.                  cursor at the beginning of line 151 and pressing
  347.                  <enter> once for each new line to be inserted.  Note,
  348.                  this will forever change the line references in
  349.                  DIRECTOR.BAT, however, you may still use DIRECTOR.TXT
  350.                  as a reference.
  351.             ∙    If you want your program to operate in some other
  352.                  directory you should enter the text 'CD \SOMEDIRNAME'
  353.                  on its on blank line.
  354.             ∙    On another blank line add the name of the program to
  355.                  execute.  If the program is a batch file, the name of
  356.                  the batch file must be preceded by the word 'CALL '
  357.                  (note the trailing space).  Therefore, 'CALL YOURBAT'.
  358.                  If your program is a COM or EXE file, simply type
  359.                  'YOURPROG'.
  360.  
  361.        That's all there is to it - save the file and execute the
  362.        DIRECTOR with your preferred parameters.
  363.  
  364.        As you can see, the options are quite diverse - you can change
  365.        DIRECTOR.BAT to suit any situation or menu requirement.  The best
  366.        news of all is that the process is compatible with all programs,
  367.        performs very quickly and requires no resident memory - unless of
  368.        course you aren't already using ANSI.SYS which does require 4K of
  369.        resident memory (see file README).
  370.  
  371.        BATMOUSE.COM and DIRECTOR.BAT are available through some BBS's
  372.        and the larger shareware distributors.
  373.  
  374.        Nick Makris is a small business consultant and systems engineer
  375.        on the North Coast of California.  For a 'no-nonsense', fully
  376.        registered version of BATMOUSE, the corresponding files and
  377.        current version of this documentation, send a check for $10.00
  378.        (including $1.00 P/H) to:
  379.  
  380.                  Startech Systems
  381.                  BATMOUSE
  382.                  PO BOX 1395
  383.                  Gualala CA, 95445-1395
  384.  
  385.        California residents add appropriate sales tax.
  386.